Error Handling

Error Response Structure

When a request fails, the API returns HTTP 200 with success: false and an error object in the response body.

{
  "success": false,
  "error": {
    "code": 102,
    "message": "Invalid results_endpoint"
  }
}

For error code 114, an additional missing_ids field is included:

{
  "success": false,
  "error": {
    "code": 114,
    "message": "One or more Blink Receipt IDs was not found",
    "missing_ids": "BR-AAAA-1111,BR-BBBB-2222"
  }
}

Error Object Fields

Field	Type	Description
code	integer	Numeric error code identifying the problem
message	string	Human-readable description of the error
missing_ids	string	Comma-separated list of receipt IDs that were not found (error 114 only)

---

Error Code Reference

General Errors

Code	Message	Description
100	Invalid input	The request body is malformed or contains an unrecognized field
101	Invalid api-key	The api-key header is missing or does not match any active key

Configuration Errors

These errors are returned by POST /ereceipts/config.

Code	Message	Description
102	Invalid results_endpoint	The results_endpoint value is not a valid, reachable URL
103	One or more retailers missing emails key	A retailer object in the retailers array is missing the required email field
104	Both global day_cutoff and date_cutoff specified	You provided both day_cutoff and date_cutoff at the top level; use only one
105	Neither global day_cutoff nor date_cutoff specified	You must provide either day_cutoff or date_cutoff at the top level
106	Global day_cutoff is not an integer	The day_cutoff field must be a whole number
107	Global date_cutoff is not an integer	The date_cutoff field must be a whole number (UNIX timestamp)
108	One or more retailers contains both day_cutoff and date_cutoff	A retailer object specifies both cutoff types; use only one per retailer
109	One or more retailers contains a day_cutoff that is not an integer	A retailer's day_cutoff value must be a whole number
110	One or more retailers contains a date_cutoff that is not an integer	A retailer's date_cutoff value must be a whole number (UNIX timestamp)
111	No retailers specified	The retailers array was included but contains no entries

Reprocessing Errors

These errors are returned by POST /ereceipts/reprocess_job.

Code	Message	Description
112	You must specify either blink_receipt_ids or retailers for reprocessing	Neither field was provided; at least one is required
113	You cannot specify both blink_receipt_ids and retailers for reprocessing	Both fields were provided; supply exactly one
114	One or more Blink Receipt IDs was not found	At least one ID in blink_receipt_ids does not exist; the missing_ids field lists the unknown IDs

---

Handling Common Errors

101 — Invalid API Key

Verify that the api-key header is present in every request and matches the key issued to your account. API keys are case-sensitive.

curl -X GET https://sandbox.blinkreceipt.com/ereceipts/config \
  -H "api-key: YOUR_CORRECT_API_KEY"

102 — Invalid results_endpoint

The webhook URL must be a valid HTTPS URL that is publicly reachable. Ensure the URL does not point to localhost or a private network address in production.

{
  "results_endpoint": "https://your-server.com/webhooks/ereceipts"
}

104 / 105 — Cutoff Configuration

You must supply exactly one of day_cutoff or date_cutoff at the global level, not both and not neither. The same constraint applies per retailer in the retailers array.

{
  "results_endpoint": "https://your-server.com/webhooks/ereceipts",
  "day_cutoff": 14
}

112 / 113 — Reprocessing Conflict

When calling POST /ereceipts/reprocess_job, supply either blink_receipt_ids or retailers, but not both.

{ "blink_receipt_ids": ["BR-AAAA-1111"] }

114 — Receipt ID Not Found

Check the missing_ids field in the error response to identify which IDs are invalid. These may have been deleted, belong to a different account, or contain a typo.

{
  "success": false,
  "error": {
    "code": 114,
    "message": "One or more Blink Receipt IDs was not found",
    "missing_ids": "BR-AAAA-1111"
  }
}

---

Job-Level Errors

Errors that occur during async processing (after a job is created) are reported in the job_status object returned by GET /ereceipts/status, not in the top-level error envelope.

{
  "success": true,
  "job_status": {
    "id": 98765,
    "status": "error",
    "error_code": 100,
    "error_message": "Failed to parse EML content"
  }
}

Check both the HTTP response error envelope and the job_status error fields when diagnosing failures. For the full list of job status values, see endpoints.md.